home *** CD-ROM | disk | FTP | other *** search
/ The CICA Windows Explosion! / The CICA Windows Explosion! - Disc 2.iso / demo / wemdemo4.zip / INFO / ELISP.9 < prev    next >
Text File  |  1994-09-21  |  50KB  |  1,213 lines
  1. Info file elisp, produced by Makeinfo, -*- Text -*- from input file
  2. elisp.texi.
  3.  
  4.    This file documents GNU Emacs Lisp.
  5.  
  6.    This is edition 1.03 of the GNU Emacs Lisp Reference Manual,   for
  7. Emacs Version 18.
  8.  
  9.    Published by the Free Software Foundation, 675 Massachusetts
  10. Avenue,  Cambridge, MA 02139 USA
  11.  
  12.    Copyright (C) 1990 Free Software Foundation, Inc.
  13.  
  14.    Permission is granted to make and distribute verbatim copies of
  15. this manual provided the copyright notice and this permission notice
  16. are preserved on all copies.
  17.  
  18.    Permission is granted to copy and distribute modified versions of
  19. this manual under the conditions for verbatim copying, provided that
  20. the entire resulting derived work is distributed under the terms of a
  21. permission notice identical to this one.
  22.  
  23.    Permission is granted to copy and distribute translations of this
  24. manual into another language, under the above conditions for modified
  25. versions, except that this permission notice may be stated in a
  26. translation approved by the Foundation.
  27.  
  28.  
  29. 
  30. File: elisp,  Node: Disassembly,  Prev: Compilation Functions,  Up: Byte Compilation
  31.  
  32. Disassembled Byte-Code
  33. ======================
  34.  
  35.    People do not write byte-code; that job is left to the byte
  36. compiler.  But we provide a disassembler to satisfy a cat-like
  37. curiosity.  The disassembler converts the byte-compiled code into
  38. humanly readable form.
  39.  
  40.    The byte-code interpreter is implemented as a simple stack machine.
  41. Values get stored by being pushed onto the stack, and are popped off
  42. and manipulated, the results being pushed back onto the stack.  When
  43. a function returns, the top of the stack is popped and returned as
  44. the value of the function.
  45.  
  46.    In addition to the stack, values used during byte-code execution
  47. can be stored in ordinary Lisp variables.  Variable values can be
  48. pushed onto the stack, and variables can be set by popping the stack.
  49.  
  50.  * Command: disassemble OBJECT &optional STREAM
  51.      This function prints the disassembled code for OBJECT.  If
  52.      STREAM is supplied, then output goes there.  Otherwise, the
  53.      disassembled code is printed to the stream `standard-output'. 
  54.      The argument OBJECT can be a function name or a lambda expression.
  55.  
  56.      As a special exception, if this function is used interactively,
  57.      it outputs to a buffer named `*Disassemble*'.
  58.  
  59.    Here are two examples of using the `disassemble' function.  We
  60. have added explanatory comments to help you relate the byte-code to
  61. the Lisp source; these do not appear in the output of `disassemble'.
  62.  
  63.         (defun factorial (integer)
  64.        "Compute factorial of an integer."
  65.        (if (= 1 integer) 1
  66.          (* integer (factorial (1- integer)))))
  67.           => factorial
  68.      
  69.      (factorial 4)
  70.           => 24
  71.      
  72.      (disassemble 'factorial)
  73.           -| byte-code for factorial:
  74.       doc: Compute factorial of an integer.
  75.       args: (integer)
  76.  
  77.  
  78.           0   constant 1              ; Push 1 onto stack.
  79.      
  80.      1   varref   integer        ; Get value of `integer' from the environment
  81.                                  ;     and push the value onto the stack.
  82.      
  83.      2   eqlsign                 ; Pop top two values off stack,
  84.                                  ;     compare them,
  85.                                  ;     and push result onto stack.
  86.      
  87.      3   goto-if-nil 10          ; Pop and test top of stack;
  88.                                  ;     if `nil', go to 10,
  89.                                  ;     else continue.
  90.      
  91.      6   constant 1              ; Push 1 onto top of stack.
  92.      
  93.      7   goto     17             ; Go to 17 (in this case, 1 will be
  94.                                  ;     returned by the function).
  95.      
  96.      10  constant *              ; Push symbol `*' onto stack.
  97.      
  98.      11  varref   integer        ; Push value of `integer' onto stack.
  99.      
  100.      12  constant factorial      ; Push `factorial' onto stack.
  101.      
  102.      13  varref   integer        ; Push value of `integer' onto stack.
  103.      
  104.      14  sub1                    ; Pop `integer', decrement value,
  105.                                  ;     push new value onto stack.
  106.      
  107.                              ; Stack now contains:
  108.                              ;     decremented value of `integer'
  109.                              ;     `factorial' 
  110.                              ;     value of `integer'
  111.                              ;     `*'
  112.      
  113.      15  call     1              ; Call function `factorial' using
  114.                                  ;     the first (i.e., the top) element
  115.                                  ;     of the stack as the argument;
  116.                                  ;     push returned value onto stack.
  117.      
  118.                              ; Stack now contains:
  119.                              ;        result of result of recursive
  120.                              ;             call to `factorial'
  121.                              ;        value of `integer'
  122.                              ;        `*'
  123.      
  124.      16  call     2              ; Using the first two (i.e., the top two)
  125.                                  ;     elements of the stack as arguments,
  126.                                  ;     call the function `*',
  127.                                  ;     pushing the result onto the stack.
  128.      
  129.      17  return                  ; Return the top element of the stack.
  130.      
  131.           => nil
  132.  
  133.    The `silly-loop' function is somewhat more complex:
  134.  
  135.      (defun silly-loop (n)
  136.        "Return time before and after N iterations of a loop."
  137.        (let ((t1 (current-time-string)))
  138.          (while (> (setq n (1- n)) 
  139.                    0))
  140.          (list t1 (current-time-string))))
  141.           => silly-loop
  142.      
  143.      (disassemble 'silly-loop)
  144.           -| byte-code for silly-loop:
  145.       doc: Return time before and after N iterations of a loop.
  146.       args: (n)
  147.      
  148.      0   constant current-time-string      ; Push `current-time-string'
  149.                                            ;     onto top of stack.
  150.      
  151.      1   call     0              ; Call `current-time-string' with no
  152.                                  ;     argument, pushing result onto stack.
  153.      
  154.      2   varbind  t1             ; Pop stack and bind `t1' to popped value.
  155.      
  156.      3   varref   n              ; Get value of `n' from the environment
  157.                                  ;     and push the value onto the stack.
  158.      
  159.      4   sub1                    ; Subtract 1 from top of stack.
  160.      
  161.      5   dup                     ; Duplicate the top of the stack;
  162.                                  ;     i.e. copy the top of the stack
  163.                                  ;     and push the copy onto the stack.
  164.      
  165.      6   varset   n              ; Pop the top of the stack,
  166.                                  ;     and bind `n' to the value.
  167.      
  168.                          ; In effect, the sequence `dup varset' copies
  169.                          ; the top of the stack into the value of `n'
  170.                          ; without popping it.
  171.      
  172.      7   constant 0              ; Push 0 onto stack.
  173.      
  174.      8   gtr                     ; Pop top two values off stack,
  175.                                  ;     test if N is greater than 0
  176.                                  ;     and push result onto stack.
  177.      
  178.      9   goto-if-nil-else-pop 17     ; Goto 17 if `n' > 0 else pop top of stack and continue
  179.                                      ;     (this exits the while loop).
  180.      
  181.      12  constant nil            ; Push `nil' onto stack
  182.                                  ;     (this is the body of the loop).
  183.      
  184.      13  discard                 ; Discard result of the body of the loop
  185.                                  ;     (a while loop is always evaluated
  186.                                  ;     for its side effects).
  187.      
  188.      14  goto     3              ; Jump back to beginning of while loop.
  189.      
  190.      17  discard                 ; Discard result of while loop
  191.                                  ;     by popping top of stack.
  192.      
  193.      18  varref   t1             ; Push value of `t1' onto stack.
  194.      
  195.      19  constant current-time-string      ; Push `current-time-string'
  196.                                            ;     onto top of stack.
  197.      
  198.      20  call     0              ; Call `current-time-string' again.
  199.      
  200.      21  list2                   ; Pop top two elements off stack,
  201.                                  ;     create a list of them,
  202.                                  ;     and push list onto stack.
  203.      
  204.      22  unbind   1              ; Unbind `t1' in local environment.
  205.      
  206.      23  return                  ; Return value of the top of stack.
  207.      
  208.           => nil
  209.  
  210.  
  211. 
  212. File: elisp,  Node: Debugging,  Next: Streams,  Prev: Byte Compilation,  Up: Top
  213.  
  214. Debugging Lisp Programs
  215. ***********************
  216.  
  217.    There are three ways to investigate a problem in an Emacs Lisp
  218. program, depending on what you are doing with the program when the
  219. problem appears.
  220.  
  221.    * If the problem occurs when you run the program, you can use the
  222.      Lisp debugger to investigate what is happening during execution.
  223.  
  224.    * If the problem is syntactic, so that Lisp cannot even read the
  225.      program, you can use the Emacs facilities for editing Lisp to
  226.      localize it.
  227.  
  228.    * If the problem occurs when trying to compile the program with
  229.      the byte compiler, you need to know how to examine the
  230.      compiler's input buffer.
  231.  
  232. * Menu:
  233.  
  234. * Debugger::            How the Emacs Lisp debugger is implemented.
  235. * Syntax Errors::       How to find syntax errors.
  236. * Compilation Errors::  How to find errors that show up in byte compilation.
  237.  
  238.     Another useful debugging tool is a dribble file.  When a dribble
  239. file is open, Emacs copies all keyboard input characters to that file.
  240. Afterward, you can examine the file to find out what input was used. 
  241. *Note Terminal Input::.
  242.  
  243.    For debugging problems in terminal descriptions, the
  244. `open-termscript' function can be useful.  *Note Terminal Output::.
  245.  
  246.  
  247. 
  248. File: elisp,  Node: Debugger,  Next: Syntax Errors,  Prev: Debugging,  Up: Debugging
  249.  
  250. The Lisp Debugger
  251. =================
  252.  
  253.    The "Lisp debugger" provides you with the ability to suspend
  254. evaluation of a form.  While evaluation is suspended (a state that is
  255. commonly known as a "break"), you may examine the run time stack,
  256. examine the values of local or global variables, or change those
  257. values.  Since a break is a recursive edit, all the usual editing
  258. facilities of Emacs are available; you can even run programs that
  259. will enter the debugger recursively.  *Note Recursive Editing::.
  260.  
  261. * Menu:
  262.  
  263. * Error Debugging::       Entering the debugger when an error happens.
  264. * Infinite Loops::      Stopping and debugging a program that doesn't exit.
  265. * Function Debugging::    Entering it when a certain function is called.
  266. * Explicit Debug::        Entering it at a certain point in the program.
  267. * Using Debugger::        What the debugger does; what you see while in it.
  268. * Debugger Commands::     Commands used while in the debugger.
  269. * Invoking the Debugger:: How to call the function `debug'.
  270. * Internals of Debugger:: Subroutines of the debugger, and global variables.
  271.  
  272.  
  273. 
  274. File: elisp,  Node: Error Debugging,  Next: Infinite Loops,  Prev: Debugger,  Up: Debugger
  275.  
  276. Entering the Debugger When an Error Occurs
  277. ------------------------------------------
  278.  
  279.    The most important time to enter the debugger is when a Lisp error
  280. happens.  This allows you to investigate the immediate causes of the
  281. error.
  282.  
  283.    However, entry to the debugger is not a normal consequence of an
  284. error.  Many commands frequently get Lisp errors when invoked in
  285. inappropriate contexts (such as `C-f' at the end of the buffer) and
  286. during ordinary editing it would be very unpleasant to enter the
  287. debugger each time this happens.  If you want errors to enter the
  288. debugger, set the variable `debug-on-error' to non-`nil'.
  289.  
  290.  * User Option: debug-on-error
  291.      This variable determines whether the debugger is called when a
  292.      error is signaled and not handled.  If `debug-on-error' is
  293.      non-`nil', then the debugger is called when an error happens. 
  294.      Otherwise the debugger is not called for errors.
  295.  
  296.  
  297. 
  298. File: elisp,  Node: Infinite Loops,  Next: Function Debugging,  Prev: Error Debugging,  Up: Debugger
  299.  
  300. Debugging Infinite Loops
  301. ========================
  302.  
  303.    When a program loops infinitely and fails to return, your first
  304. problem is to stop the loop.  On most operating systems, you can do
  305. this with `C-g', which causes quit.  This works if you are not using
  306. X windows, and on Berkeley systems even if you are using X windows.
  307.  
  308.    On other inferior operating systems, `C-g' does not work when
  309. using X windows.  This is because these systems do not allow Emacs to
  310. request a signal when input arrives from the X server.  There is
  311. nothing Emacs can do about this.
  312.  
  313.    However, you can still stop a loop by sending Emacs the `SIGINT'
  314. signal.  To do this, go to a shell in another window, use `ps' to
  315. find out the PID of the Emacs process, and then type `kill -INT PID'.
  316.  
  317.    Ordinary quitting gives no information about why the program was
  318. looping.  To get more information, you can set the variable
  319. `debug-on-quit' to non-`nil'.  Quitting with `C-g' is not considered
  320. an error, and `debug-on-error' has no effect on the handling of
  321. `C-g'.  `debug-on-quit' has no effect on errors.
  322.  
  323.    Once you have the debugger running in the middle of the infinite
  324. loop, you can proceed from the debugger using the stepping commands. 
  325. If you step through the entire loop, you will probably get enough
  326. information to solve the problem.
  327.  
  328.  * User Option: debug-on-quit
  329.      This variable determines whether the debugger is called when
  330.      `quit' is signaled and not handled.  If `debug-on-quit' is
  331.      non-`nil', then the debugger is called whenever you quit (that
  332.      is, type `C-g').  If `debug-on-quit' is `nil', then the debugger
  333.      is not called when you quit.  *Note Quitting::.
  334.  
  335.  
  336. 
  337. File: elisp,  Node: Function Debugging,  Next: Explicit Debug,  Prev: Infinite Loops,  Up: Debugger
  338.  
  339. Entering the Debugger when Some Function is Called
  340. --------------------------------------------------
  341.  
  342.    To investigate a problem that happens in the middle of a program,
  343. one useful technique is to cause the debugger to be entered when a
  344. certain function is called.  You can do this to the function in which
  345. the problem occurs, and then step through the function, or you can do
  346. this to a function called shortly before the problem, step quickly
  347. over the call to that function, and then step through its caller.
  348.  
  349.  * Command: debug-on-entry FUNCTION-NAME
  350.      This function requests FUNCTION-NAME to invoke the debugger each
  351.      time it is called.  It works by inserting the form `(debug
  352.      'debug)' into the function definition as the first form.
  353.  
  354.      Any function defined as Lisp code may be set to break on entry,
  355.      regardless of whether it is interpreted code or compiled code. 
  356.      Even functions that are commands may be debugged--they will
  357.      enter the debugger when called inside a function, or when called
  358.      interactively.  Primitive functions (i.e., those written in C)
  359.      may not be debugged.
  360.  
  361.      When `debug-on-entry' is called interactively, it prompts for
  362.      FUNCTION-NAME in the minibuffer.
  363.  
  364.      If `debug-on-entry' is called more than once on the same
  365.      function, the second call does nothing.  `debug-on-entry'
  366.      returns FUNCTION-NAME.
  367.  
  368.           (defun fact (n)
  369.             (if (zerop n) 1
  370.                 (* n (fact (1- n)))))
  371.                => fact
  372.           (debug-on-entry 'fact)
  373.                => fact
  374.           (fact 3)
  375.                => 6
  376.           
  377.           ---------- Buffer: *Backtrace* ----------
  378.           Entering:
  379.           * fact(3)
  380.             eval-region(4870 4878 t)
  381.             byte-code("...")
  382.             eval-last-sexp(nil)
  383.             (let ...)
  384.             eval-insert-last-sexp(nil)
  385.           * call-interactively(eval-insert-last-sexp)
  386.           ---------- Buffer: *Backtrace* ----------
  387.           
  388.           (symbol-function 'fact)
  389.                => (lambda (n)
  390.                     (debug (quote debug))
  391.                     (if (zerop n) 1 (* n (fact (1- n)))))
  392.  
  393.  * Command: cancel-debug-on-entry FUNCTION-NAME
  394.      This function undoes the effect of `debug-on-entry' on
  395.      FUNCTION-NAME.  When called interactively, it prompts for
  396.      FUNCTION-NAME in the minibuffer.
  397.  
  398.      If `cancel-debug-on-entry' is called more than once on the same
  399.      function, the second call does nothing.  `cancel-debug-on-entry'
  400.      returns FUNCTION-NAME.
  401.  
  402.  
  403. 
  404. File: elisp,  Node: Explicit Debug,  Next: Using Debugger,  Prev: Function Debugging,  Up: Debugger
  405.  
  406. Explicit Entry to the Debugger
  407. ------------------------------
  408.  
  409.    You can cause the debugger to be called at a certain point in your
  410. program by writing the expression `(debug)' at that point.  To do
  411. this, visit the source file, insert the text `(debug)' at the proper
  412. place, and type `C-M-x'.  Be sure to undo this insertion before you
  413. save the file!
  414.  
  415.    The place where you insert `(debug)' must be a place where an
  416. additional form can be evaluated and its value ignored.  (If the
  417. value isn't ignored, it will alter the execution of the program!) 
  418. Usually this means inside a `progn' or an implicit `progn' (*note
  419. Sequencing::.).
  420.  
  421.  
  422. 
  423. File: elisp,  Node: Using Debugger,  Next: Debugger Commands,  Prev: Explicit Debug,  Up: Debugger
  424.  
  425. Using the Debugger
  426. ------------------
  427.  
  428.    When the debugger is entered, it displays the previously selected
  429. buffer in one window and a buffer named `*Backtrace*' in another
  430. window.  The backtrace buffer contains one line for each level of
  431. Lisp function execution currently going on.  At the beginning of this
  432. buffer is a message describing the reason that the debugger was
  433. invoked (such as the error message and associated data, if it was
  434. invoked due to an error).
  435.  
  436.    The backtrace buffer is read-only and uses a special major mode,
  437. Debugger mode, in which letters are defined as debugger commands. 
  438. The usual Emacs editing commands are available; thus, you can switch
  439. windows to examine the buffer that was being edited at the time of
  440. the error, switch buffers, visit files, or do any other sort of
  441. editing.  However, the debugger is a recursive editing level (*note
  442. Recursive Editing::.) and it is wise to go back to the backtrace
  443. buffer and exit the debugger (with the `q' command) when you you are
  444. finished with it.  Exiting the debugger gets out of the recursive
  445. edit and kills the backtrace buffer.
  446.  
  447.    The contents of the backtrace buffer show you the functions that
  448. are executing and the arguments that were given to them.  It also
  449. allows you to specify a stack frame by moving point to the line
  450. describing that frame.  (A stack frame is the place where the Lisp
  451. interpreter records information about a particular invocation of a
  452. function.  The frame whose line point is on is considered the
  453. "current frame".) Some of the debugger commands operate on the
  454. current frame.
  455.  
  456.    The debugger itself should always be run byte-compiled, since it
  457. makes assumptions about how many stack frames are used for the
  458. debugger itself.  These assumptions are false if the debugger is
  459. running interpreted.
  460.  
  461.  
  462. 
  463. File: elisp,  Node: Debugger Commands,  Next: Invoking the Debugger,  Prev: Using Debugger,  Up: Debugger
  464.  
  465. Debugger Commands
  466. -----------------
  467.  
  468.    Inside the debugger (in Debugger mode), these special commands are
  469. available in addition to the usual cursor motion commands.  (Keep in
  470. mind that all the usual facilities of Emacs, such as switching
  471. windows or buffers, are still available.)
  472.  
  473.    The most important use of debugger commands is for stepping
  474. through code, so that you can see how control flows.  The debugger
  475. can step through the control structures of an interpreted function,
  476. but cannot do so in a byte-compiled function.  If you would like to
  477. step through a byte-compiled function, replace it with an interpreted
  478. definition of the same function.  (To do this, visit the source file
  479. for the function and type `C-M-x' on its definition.)
  480.  
  481. `c'
  482.      Exit the debugger and continue execution.  When continuing is
  483.      possible, it resumes execution of the program as if the debugger
  484.      had never been entered (aside from the effect of any variables
  485.      or data structures you may have changed while inside the
  486.      debugger).
  487.  
  488.      Continuing is possible after entry to the debugger due to
  489.      function entry or exit, explicit invocation, quitting or certain
  490.      errors.  Most errors cannot be continued; trying to continue an
  491.      unsuitable error causes the same error to occur again.
  492.  
  493. `d'
  494.      Continue execution, but enter the debugger the next time any
  495.      Lisp function is called.  This allows you to step through the
  496.      subexpressions of an expression, seeing what values the
  497.      subexpressions compute, and what else they do.
  498.  
  499.      The stack frame made for the function call which enters the
  500.      debugger in this way will be flagged automatically so that the
  501.      debugger will be called again when the frame is exited.  You can
  502.      use the `u' command to cancel this flag.
  503.  
  504. `b'
  505.      Flag the current frame so that the debugger will be entered when
  506.      the frame is exited.  Frames flagged in this way are marked with
  507.      stars in the backtrace buffer.
  508.  
  509. `u'
  510.      Don't enter the debugger when the current frame is exited.  This
  511.      cancels a `b' command on that frame.
  512.  
  513. `e'
  514.      Read a Lisp expression in the minibuffer, evaluate it, and print
  515.      the value in the echo area.  This is the same as the command
  516.      `M-ESC', except that `e' is not normally disabled like `M-ESC'.
  517.  
  518. `q'
  519.      Terminate the program being debugged; return to top-level Emacs
  520.      command execution.
  521.  
  522.      If the debugger was entered due to a `C-g' but you really want
  523.      to quit, and not debug, use the `q' command.
  524.  
  525. `r'
  526.      Return a value from the debugger.  The value is computed by
  527.      reading an expression with the minibuffer and evaluating it.
  528.  
  529.      The `r' command makes a difference when the debugger was invoked
  530.      due to exit from a Lisp call frame (as requested with `b'); then
  531.      the value specified in the `r' command is used as the value of
  532.      that frame.
  533.  
  534.      The `r' also matters in certain cases of errors.  For example,
  535.      `wrong-type-argument' errors will use the debugger's return
  536.      value instead of the invalid argument; `no-catch' errors will
  537.      use the debugger value as a throw tag instead of the tag that
  538.      was not found.  If an error was signaled by calling the Lisp
  539.      function `signal', the debugger's return value is returned as
  540.      the value of `signal'.
  541.  
  542.  
  543. 
  544. File: elisp,  Node: Invoking the Debugger,  Next: Internals of Debugger,  Prev: Debugger Commands,  Up: Debugger
  545.  
  546. Invoking the Debugger
  547. ---------------------
  548.  
  549.    Here we describe fully the function used to invoke the debugger.
  550.  
  551.  * Function: debug &rest DEBUGGER-ARGS
  552.      This function enters the debugger.  It switches buffers to a
  553.      buffer named `*Backtrace*' (or `*Backtrace*<2>' if it is the
  554.      second recursive entry to the debugger, etc.), and fills it with
  555.      information about the stack of Lisp function calls.  It then
  556.      enters a recursive edit, leaving that buffer in Debugger mode
  557.      and displayed in the selected window.
  558.  
  559.      Debugger mode provides a `c' command which operates by exiting
  560.      the recursive edit, switching back to the previous buffer, and
  561.      returning to whatever called `debug'.  The `r' command also
  562.      returns from `debug'.  These are the only ways the function
  563.      `debug' can return to its caller.
  564.  
  565.      If the first of the DEBUGGER-ARGS passed to `debug' is `nil' (or
  566.      if it is not one of the following special values), then the rest
  567.      of the arguments to `debug' are printed at the top of the
  568.      `*Backtrace*' buffer.  This mechanism is used to display a
  569.      message to the user.
  570.  
  571.      However, if the first argument passed to `debug' is one of the
  572.      following special values, then it has special significance. 
  573.      Normally, these values are passed to `debug' only by the
  574.      internals of Emacs and the debugger, and not by programmers
  575.      calling `debug'.
  576.  
  577.      The special values are:
  578.  
  579.     `lambda'
  580.           When the first argument is `lambda', the debugger displays
  581.           `Entering:' as a line of text at the top of the buffer. 
  582.           This means that a function is being entered when
  583.           `debug-on-next-call' is non-`nil'.
  584.  
  585.     `debug'
  586.           When the first argument is `debug', the debugger displays
  587.           `Entering:' just as in the `lambda' case.  However, `debug'
  588.           as the argument indicates that the reason for entering the
  589.           debugger is that a function set to debug on entry is being
  590.           entered.
  591.  
  592.           In addition, `debug' as the first argument directs the
  593.           debugger to mark the function that called `debug' so that
  594.           it will invoke the debugger when exited.  (When `lambda' is
  595.           the first argument, the debugger does not do this, because
  596.           it has already been done by the interpreter.)
  597.  
  598.     `t'
  599.           When the first argument is `t', the debugger displays
  600.           `Beginning evaluation of function call form:' as the top
  601.           line in the buffer, to indicate that it was entered due to
  602.           the evaluation of a list form at a time when
  603.           `debug-on-next-call' is non-`nil'.
  604.  
  605.     `exit'
  606.           When the first argument is `exit', it indicates the exit of
  607.           a stack frame previously marked to invoke the debugger on
  608.           exit.  The debugger displays `Return value:' on the top
  609.           line of the buffer, followed by the value being returned
  610.           from the frame.
  611.  
  612.     `error'
  613.           When the first argument is `error', the debugger indicates
  614.           that it is being entered because an error or `quit' was
  615.           signaled and not handled, by displaying `Signaling:'
  616.           followed by the error signaled and any arguments to
  617.           `signal'.  For example,
  618.  
  619.                (let ((debug-on-error t))
  620.                     (/ 1 0))
  621.                
  622.                ---------- Buffer: *Backtrace* ----------
  623.                Signaling: (arith-error)
  624.                  /(1 0)
  625.                ...
  626.  
  627.            If an error was signaled, presumably the variable
  628.           `debug-on-error' is non-`nil'.  If `quit' was signaled,
  629.           then presumably the variable `debug-on-quit' is non-`nil'.
  630.  
  631.     `nil'
  632.           Use `nil' as the first of the DEBUGGER-ARGS when you want
  633.           to enter the debugger explicitly.  The rest of the
  634.           DEBUGGER-ARGS are printed on the top line of the buffer. 
  635.           You can use this feature to display messages--for example,
  636.           to remind yourself of the conditions under which `debug' is
  637.           called.
  638.  
  639.  
  640. 
  641. File: elisp,  Node: Internals of Debugger,  Prev: Invoking the Debugger,  Up: Debugger
  642.  
  643. Internals of the Debugger
  644. -------------------------
  645.  
  646.    This section describes functions and variables used internally by
  647. the debugger.
  648.  
  649.  * Variable: debugger
  650.      The value of this variable is the function to call to invoke the
  651.      debugger.  Its value must be a function of any number of
  652.      arguments (or, more typically, the name of a function). 
  653.      Presumably this function will enter some kind of debugger.  The
  654.      default value of the variable is `debug'.
  655.  
  656.      The first argument that Lisp hands to the function indicates why
  657.      it was called.  The convention for arguments is detailed in the
  658.      description of `debug'.
  659.  
  660.  * Command: backtrace
  661.      This function prints a trace of Lisp function calls currently
  662.      active.  This is the function used by `debug' to fill up the
  663.      `*Backtrace*' buffer.  It is written in C, since it must have
  664.      access to the stack to determine which function calls are
  665.      active.  The return value is always `nil'.
  666.  
  667.      In the following example, `backtrace' is called explicitly in a
  668.      Lisp expression.  When the expression is evaluated, the
  669.      backtrace is printed to the stream `standard-output': in this
  670.      case, to the buffer `backtrace-output'.  Each line of the
  671.      backtrace represents one function call.  If the arguments of the
  672.      function call are all known, they are displayed; if they are
  673.      being computed, that fact is stated.  The arguments of special
  674.      forms are elided.
  675.  
  676.           (with-output-to-temp-buffer "backtrace-output"
  677.             (let ((var 1))
  678.               (save-excursion
  679.                 (setq var (eval '(progn
  680.                                    (1+ var)
  681.                                    (list 'testing (backtrace))))))))
  682.           
  683.                => nil
  684.           ----------- Buffer: backtrace-output ------------
  685.             backtrace()
  686.             (list ...computing arguments...)
  687.             (progn ...)
  688.             eval((progn (1+ var) (list (quote testing) (backtrace))))
  689.             (setq ...)
  690.             (save-excursion ...)
  691.             (let ...)
  692.             (with-output-to-temp-buffer ...)
  693.             eval-region(1973 2142 #<buffer *scratch*>)
  694.             byte-code("...  for eval-print-last-sexp ...")
  695.             eval-print-last-sexp(nil)
  696.           * call-interactively(eval-print-last-sexp)
  697.           ----------- Buffer: backtrace-output ------------
  698.  
  699.  * User Option: stack-trace-on-error
  700.      This variable controls whether Lisp automatically displays a
  701.      backtrace buffer after every error that is not handled.  A quit
  702.      signal counts as an error for this variable.  If it is non-`nil'
  703.      then a backtrace is shown in a pop-up buffer named `*Backtrace*'
  704.      on every error.  If it is `nil', then a backtrace is not shown.
  705.  
  706.      When a backtrace is shown, that buffer is not selected.  If
  707.      either `debug-on-quit' or `debug-on-error' is also non-`nil',
  708.      then a backtrace is shown in one buffer, and the debugger is
  709.      popped up in another buffer with its own backtrace.
  710.  
  711.      We consider this feature to be obsolete and superseded by the
  712.      debugger itself.
  713.  
  714.  * Variable: debug-on-next-call
  715.      This variable determines whether the debugger is called before
  716.      the next `eval', `apply' or `funcall'.  It is automatically
  717.      reset to `nil' when the debugger is entered.
  718.  
  719.      The `d' command in the debugger works by setting this variable.
  720.  
  721.  * Function: backtrace-debug LEVEL FLAG
  722.      This function sets the debug-on-exit flag of the eval frame
  723.      LEVEL levels down to FLAG.  If FLAG is non-`nil', this will
  724.      cause the debugger to be entered when that frame exits.
  725.  
  726.      The debug-on-exit flag is an entry in the stack frame of a
  727.      function call.  This flag is examined on every exit from a
  728.      function.
  729.  
  730.      Normally, this function is only called by the debugger.
  731.  
  732.  
  733. 
  734. File: elisp,  Node: Syntax Errors,  Next: Compilation Errors,  Prev: Debugger,  Up: Debugging
  735.  
  736. Debugging Invalid Lisp Syntax
  737. =============================
  738.  
  739.    It is easy to make a syntax error in an Emacs Lisp program by
  740. omitting a parenthesis.  The Lisp reader will detect an error, but
  741. cannot say where the real problem is.  For example, if a close
  742. parenthesis is omitted, the reader will detect an imbalance at the
  743. end of the file, but it cannot tell anything about where the close
  744. parenthesis should have been.  However, you can use the following
  745. techniques to figure out where.
  746.  
  747.    If the problem is not simply an imbalance of parentheses, a useful
  748. technique is to try `C-M-e' at the beginning of each defun, and see
  749. if it goes to the place where that defun appears to end.  If it does
  750. not, there is a problem in that defun.
  751.  
  752.    However, unmatched parentheses are the most common syntax errors
  753. in Lisp, and we can give further advice for those cases.
  754.  
  755. * Menu:
  756.  
  757. * Excess Open::     How to find a spurious open paren or missing close.
  758. * Excess Close::    How to find a spurious close paren or missing open.
  759.  
  760.  
  761. 
  762. File: elisp,  Node: Excess Open,  Next: Excess Close,  Prev: Syntax Errors,  Up: Syntax Errors
  763.  
  764. Excess Open Parentheses
  765. -----------------------
  766.  
  767.    The first step is to find the defun that is unbalanced.  If there
  768. is an excess open parenthesis, the way to do this is to insert a
  769. close parenthesis at the end of the file and type `C-M-b'
  770. (`backward-sexp').  This will move you to the beginning of the defun
  771. that is unbalanced.  (Then type `C-SPC C-_ C-u C-SPC' to set the mark
  772. there, undo the insertion of the close parenthesis, and finally
  773. return to the mark.)
  774.  
  775.    The next step is to determine precisely what is wrong.  There is
  776. no way to be sure of this except to study the program, but often the
  777. existing indentation is a clue to where the parentheses should have
  778. been.  The easiest way to use this clue is to reindent with `C-M-q'
  779. and see what moves.
  780.  
  781.    Before you do this, make sure the defun has enough close
  782. parentheses.  Otherwise, `C-M-q' will get an error, or will reindent
  783. all the rest of the file until the end.  So move to the end of the
  784. defun and insert a close parenthesis there.  Don't use `C-M-e' to
  785. move there, since that too will fail to work until the defun is
  786. balanced.
  787.  
  788.    Then go to the beginning of the defun and type `C-M-q'.  Usually
  789. all the lines from a certain point to the end of the function will
  790. shift to the right.  There is probably a missing close parenthesis,
  791. or a superfluous open parenthesis, near that point.  (However, don't
  792. assume this is true; study the code to make sure.)  Once you have
  793. found the discrepancy, undo the `C-M-q', since the old indentation is
  794. probably appropriate to the intended parentheses.
  795.  
  796.    After you think you have fixed the problem, use `C-M-q' again.  It
  797. should not change anything, if the problem is really fixed.
  798.  
  799.  
  800. 
  801. File: elisp,  Node: Excess Close,  Prev: Excess Open,  Up: Syntax Errors
  802.  
  803. Excess Close Parentheses
  804. ------------------------
  805.  
  806.    To deal with an excess close parenthesis, first insert an open
  807. parenthesis at the beginning of the file and type `C-M-f' to find the
  808. end of the unbalanced defun.  (Then type `C-SPC C-_ C-u C-SPC' to set
  809. the mark there, undo the insertion of the open parenthesis, and
  810. finally return to the mark.)
  811.  
  812.    Then find the actual matching close parenthesis by typing `C-M-f'
  813. at the beginning of the defun.  This will leave you somewhere short
  814. of the place where the defun ought to end.  It is possible that you
  815. will find a spurious close parenthesis in that vicinity.
  816.  
  817.    If you don't see a problem at that point, the next thing to do is
  818. to type `C-M-q' at the beginning of the defun.  A range of lines will
  819. probably shift left; if so, the missing open parenthesis or spurious
  820. close parenthesis is probably near the first of those lines. 
  821. (However, don't assume this is true; study the code to make sure.) 
  822. Once you have found the discrepancy, undo the `C-M-q', since the old
  823. indentation is probably appropriate to the intended parentheses.
  824.  
  825.  
  826. 
  827. File: elisp,  Node: Compilation Errors,  Prev: Syntax Errors,  Up: Debugging
  828.  
  829. Debugging Problems in Compilation
  830. =================================
  831.  
  832.    When an error happens during byte compilation, it is normally due
  833. to an error in the program you are compiling.  The compiler itself
  834. can't tell you where in the file the error occurred, so here is how
  835. to find out.
  836.  
  837.    What you should do is switch to the buffer ` *Compiler Input*'. 
  838. (Note that the buffer name starts with a space, so it will not show
  839. up in `M-x list-buffers'.)  This buffer contains the program being
  840. compiled, and point shows how far the byte compiler was able to read.
  841.  
  842.    If the error was due to invalid Lisp syntax, point shows exactly
  843. where the invalid syntax was *detected*.  The cause of the error is
  844. not necessarily near by!  Use the techniques in the previous section
  845. to find the error.
  846.  
  847.    If the error was detected while compiling a form that had been
  848. read successfully, then point is located at the end of the form.  In
  849. this case, it can't localize the error precisely, but can still show
  850. you which function to check.
  851.  
  852.  
  853. 
  854. File: elisp,  Node: Streams,  Next: Minibuffers,  Prev: Debugging,  Up: Top
  855.  
  856. Reading and Printing Lisp Objects
  857. *********************************
  858.  
  859.    "Printing" and "reading" are the operations of converting Lisp
  860. objects to textual form and vice versa.  They use the printed
  861. representations and read syntax described in *Note Types of Lisp
  862. Object::.
  863.  
  864.    This chapter describes the Lisp functions for reading and printing.
  865. It also describes "streams", which specify where to get the text (if
  866. reading) or where to put it (if printing).
  867.  
  868. * Menu:
  869.  
  870. * Streams Intro::     Overview of streams, reading and printing.
  871. * Input Streams::     Various data types that can be used as input streams.
  872. * Input Functions::   Functions to read Lisp objects from text.
  873. * Output Streams::    Various data types that can be used as input streams.
  874. * Output Functions::  Functions to print Lisp objects as text.
  875.  
  876.  
  877. 
  878. File: elisp,  Node: Streams Intro,  Next: Input Streams,  Prev: Streams,  Up: Streams
  879.  
  880. Introduction to Reading and Printing
  881. ====================================
  882.  
  883.    "Reading" a Lisp object means parsing a Lisp expression in textual
  884. form and producing a corresponding Lisp object.  This is how Lisp
  885. programs get into Lisp from files of Lisp code.  We call the text the
  886. "read syntax" of the object.  For example, reading the text `(a . 5)'
  887. returns a cons cell whose CAR is `a' and whose CDR is the number 5.
  888.  
  889.    "Printing" a Lisp object means producing text that represents that
  890. object--converting the object to its printed representation. 
  891. Printing the cons cell described above produces the text `(a . 5)'.
  892.  
  893.    Reading and printing are usually inverse operations: printing the
  894. object that results from reading a given piece of text often produces
  895. the same text, and reading the text that results from printing an
  896. object usually produces a similar-looking object.  For example,
  897. printing the symbol `foo' produces the text `foo', and reading that
  898. text returns the symbol `foo'.  Printing a list whose elements are
  899. `a' and `b' produces the text `(a b)', and reading that text produces
  900. a list (but not the same list) with elements are `a' and `b'.
  901.  
  902.    However, these two operations are not precisely inverses.  There
  903. are two kinds of exceptions:
  904.  
  905.    * Printing can produce text that cannot be read.  For example,
  906.      buffers, windows, subprocesses and markers print into text that
  907.      starts with `#'; if you try to read this text, you get an error.
  908.      There is no way to read those data types.
  909.  
  910.    * One object can have multiple textual representations.  For
  911.      example, `1' and `01' represent the same integer, and `(a b)'
  912.      and `(a . (b))' represent the same list.  Reading will accept
  913.      any of the alternatives, but printing must choose one of them.
  914.  
  915.  
  916. 
  917. File: elisp,  Node: Input Streams,  Next: Input Functions,  Prev: Streams Intro,  Up: Streams
  918.  
  919. Input Streams
  920. =============
  921.  
  922.    Most of the Lisp functions for reading text take an "input stream"
  923. as an argument.  The input stream specifies where or how to get the
  924. characters of the text to be read.  Here are the possible types of
  925. input stream:
  926.  
  927. BUFFER
  928.      The input characters are read from BUFFER, starting with the
  929.      character directly after point.  Point advances as characters
  930.      are read.
  931.  
  932. MARKER
  933.      The input characters are read from the buffer that MARKER is in,
  934.      starting with the character directly after the marker.  The
  935.      marker position advances as characters are read.  The value of
  936.      point in the buffer has no effect when the stream is a marker.
  937.  
  938. STRING
  939.      The input characters are taken from STRING, starting at the
  940.      first character in the string and using as many characters as
  941.      required.
  942.  
  943. FUNCTION
  944.      The input characters are generated by FUNCTION, one character
  945.      per call.  In version 18, FUNCTION is always called with no
  946.      arguments and should return a character.
  947.  
  948. `t'
  949.      `t' used as a stream means that the input is read from the
  950.      minibuffer.  In fact, the minibuffer is invoked once and the
  951.      text given by the user is made into a string that is then used
  952.      as the input stream.
  953.  
  954. `nil'
  955.      `nil' used as a stream means that the value of `standard-input'
  956.      should be used instead; that value is the "default input
  957.      stream", and must be a non-`nil' input stream.
  958.  
  959.    Here is an example of reading from a stream which is a buffer,
  960. showing where point is located before and after:
  961.  
  962.      ---------- Buffer: foo ----------
  963.      This-!- is the contents of foo.
  964.      ---------- Buffer: foo ----------
  965.      
  966.      (read (get-buffer "foo"))
  967.           => is
  968.      (read (get-buffer "foo"))
  969.           => the
  970.      
  971.      ---------- Buffer: foo ----------
  972.      This is the -!-contents of foo.
  973.      ---------- Buffer: foo ----------
  974.  
  975. Note that the first read skips a space at the beginning of the buffer.
  976. Reading skips any amount of whitespace preceding the significant text.
  977. Note also that the second read skips the space which terminates the
  978. symbol `the'.  It has to read this space in order to know that no
  979. more letters follow.
  980.  
  981.    Here is an example of reading from a stream that is a marker,
  982. initialized to point at the beginning of the buffer shown.  The value
  983. of the read is the symbol `This'.
  984.  
  985.      ---------- Buffer: foo ----------
  986.      This is the contents of foo.
  987.      ---------- Buffer: foo ----------
  988.      
  989.      (setq m (set-marker (make-marker) 1 (get-buffer "foo")))
  990.           => #<marker at 1 in foo>
  991.      (read m)
  992.           => This
  993.      m
  994.           => #<marker at 6 in foo>   ;; After the first space.
  995.  
  996.     Here we read from the contents of a string:
  997.  
  998.      (read "(When in) the course")
  999.           => (When in)
  1000.  
  1001.    The following example reads from the minibuffer, prompting with
  1002. `Lisp expression: '.  (That is always the prompt used when you read
  1003. from the stream `t'.)  The user's input is shown following the prompt.
  1004.  
  1005.      (read t)
  1006.           => 23
  1007.      ---------- Buffer: Minibuffer ----------
  1008.      Lisp expression: `23 RET'
  1009.  
  1010.    Finally, here is an example of a stream that is a function, named
  1011. `useless-stream'.  Before we use the stream, we initialize the
  1012. variable `useless-list' to a list of characters.  Then each call to
  1013. the function `useless-stream' obtains the next letter in the list:
  1014.  
  1015.      (setq useless-list (append "XY()" nil))
  1016.           => (88 89 40 41)
  1017.      
  1018.      (defun useless-stream ()
  1019.        (prog1 (car useless-list)
  1020.               (setq useless-list (cdr useless-list))))
  1021.           => useless-stream
  1022.  
  1023. Now we read using the stream thus constructed:
  1024.  
  1025.      (read 'useless-stream)
  1026.           => XY
  1027.      
  1028.      useless-list
  1029.           => (41)
  1030.  
  1031. Note that the close parenthesis remains in the list.  This is because
  1032. the open parenthesis was read before the Lisp reader knew it had
  1033. found the end of the symbol.  A second attempt to read from the
  1034. stream at this point would get an error due to the unmatched close
  1035. parenthesis.
  1036.  
  1037.  * Function: get-file-char
  1038.      This function is used internally as an input stream to read from
  1039.      the input file opened by the function `load'.  Don't use this
  1040.      function yourself.
  1041.  
  1042.  
  1043. 
  1044. File: elisp,  Node: Input Functions,  Next: Output Streams,  Prev: Input Streams,  Up: Streams
  1045.  
  1046. Input Functions
  1047. ===============
  1048.  
  1049.    This section describes the Lisp functions and variables that
  1050. pertain to reading.
  1051.  
  1052.    In the functions below, STREAM stands for an input stream (see the
  1053. previous section).  If STREAM is `nil' or omitted, it defaults to the
  1054. value of `standard-input'.
  1055.  
  1056.    An `end-of-file' error will result if an unterminated list or
  1057. vector is found.
  1058.  
  1059.  * Function: read &optional STREAM
  1060.      This function reads one textual Lisp expression from STREAM,
  1061.      returning it as a Lisp object.  This is the basic Lisp input
  1062.      function.
  1063.  
  1064.  * Function: read-from-string STRING &optional START END
  1065.      This function reads the first textual Lisp expression from the
  1066.      text in STRING.  It returns a cons cell whose CAR is that
  1067.      expression, and whose CDR is an integer giving the position of
  1068.      the next remaining character in the string (i.e., the first one
  1069.      not read).
  1070.  
  1071.      If START is supplied, then reading begins at index START in the
  1072.      string (where the first character is at index 0).  If END is
  1073.      also supplied, then reading stops at that index as if the rest
  1074.      of the string were not there.
  1075.  
  1076.      For example:
  1077.  
  1078.           (read-from-string "(setq x 55) (setq y 5)")
  1079.                => ((setq x 55) . 11)
  1080.           (read-from-string "\"A short string\"")
  1081.                => ("A short string" . 16)
  1082.           
  1083.           ;; Read starting at the first character.
  1084.           (read-from-string "(list 112)" 0)
  1085.                => ((list 112) . 10)
  1086.           ;; Read starting at the second character.
  1087.           (read-from-string "(list 112)" 1)
  1088.                => (list . 6)
  1089.           ;; Read starting at the seventh character, and stopping at the ninth.
  1090.           (read-from-string "(list 112)" 6 8)
  1091.                => (11 . 8)
  1092.  
  1093.  * Variable: standard-input
  1094.      This variable holds the default input stream: the stream that
  1095.      `read' uses when the STREAM argument is `nil'.
  1096.  
  1097.  
  1098. 
  1099. File: elisp,  Node: Output Streams,  Next: Output Functions,  Prev: Input Functions,  Up: Streams
  1100.  
  1101. Output Streams
  1102. ==============
  1103.  
  1104.    An output stream specifies what to do with the characters produced
  1105. by printing.  Most print functions accept an output stream as an
  1106. optional argument.  Here are the possible types of output stream:
  1107.  
  1108. BUFFER
  1109.      The output characters are inserted into BUFFER at point.  Point
  1110.      advances as characters are inserted.
  1111.  
  1112. MARKER
  1113.      The output characters are inserted into the buffer that MARKER
  1114.      is in at the marker position.  The position advances as
  1115.      characters are inserted.  The value of point in the buffer has
  1116.      no effect when the stream is a marker.
  1117.  
  1118. FUNCTION
  1119.      The output characters are passed to FUNCTION, which is
  1120.      responsible for storing them away.  It is called with a single
  1121.      character as argument, as many times as there are characters to
  1122.      be output, and is free to do anything at all with the characters
  1123.      it receives.
  1124.  
  1125. `t'
  1126.      The output characters are displayed in the echo area.
  1127.  
  1128. `nil'
  1129.      `nil' specified as an output stream means that the value of
  1130.      `standard-output' should be used as the output stream; that
  1131.      value is the "default output stream", and must be a non-`nil'
  1132.      output stream.
  1133.  
  1134.    Here is an example of a buffer used as an output stream.  Point is
  1135. initially located as shown immediately before the `h' in `the'.  At
  1136. the end, point is located directly before that same `h'.
  1137.  
  1138.         ---------- Buffer: foo ----------
  1139.      This is t-!-he contents of foo.
  1140.      ---------- Buffer: foo ----------
  1141.  
  1142.  
  1143.           (print "This is the output" (get-buffer "foo"))
  1144.           => "This is the output"
  1145.  
  1146.         ---------- Buffer: foo ----------
  1147.      This is t
  1148.      "This is the output"
  1149.      -!-he contents of foo.
  1150.      ---------- Buffer: foo ----------
  1151.  
  1152.    Now we show a use of a marker as an output stream.  Initially, the
  1153. marker points in buffer `foo', between the `t' and the `h' in the
  1154. word `the'.  At the end, the marker has been advanced over the
  1155. inserted text so that it still points before the same `h'.  Note that
  1156. the location of point, shown in the usual fashion,  has no effect.
  1157.  
  1158.      ---------- Buffer: foo ----------
  1159.      "This is the -!-output"
  1160.      ---------- Buffer: foo ----------
  1161.      
  1162.      m
  1163.           => #<marker at 11 in foo>
  1164.      
  1165.      (print "More output for foo." marker)
  1166.           => "More output for foo."
  1167.      
  1168.      ---------- Buffer: foo ----------
  1169.      "This is t
  1170.      "More output for foo."
  1171.      he -!-output"
  1172.      ---------- Buffer: foo ----------
  1173.      
  1174.      m
  1175.           => #<marker at 35 in foo>
  1176.  
  1177.    The following example shows output to the echo area:
  1178.  
  1179.      (print "Echo Area output" t)
  1180.           => "Echo Area output"
  1181.      ---------- Echo Area ----------
  1182.      "Echo Area output"
  1183.      ---------- Echo Area ----------
  1184.  
  1185.    Finally, we show an output stream which is a function.  The
  1186. function `eat-output' takes each character that it is given and
  1187. conses it onto the front of the list `last-output' (*note Building
  1188. Lists::.).  At the end, the list contains all the characters output,
  1189. but in reverse order.
  1190.  
  1191.      (setq last-output nil)
  1192.           => nil
  1193.      
  1194.      (defun eat-output (c)
  1195.        (setq last-output (cons c last-output)))
  1196.           => eat-output
  1197.      
  1198.      (print "This is the output" 'eat-output)
  1199.           => "This is the output"
  1200.      
  1201.      last-output
  1202.           => (10 34 116 117 112 116 117 111 32 101 104 116 32 115 105
  1203.          32 115 105 104 84 34 10)
  1204.  
  1205. Now we can put the output in the proper order by reversing the list:
  1206.  
  1207.      (concat (nreverse last-output))
  1208.           => "
  1209.      \"This is the output\"
  1210.      "
  1211.  
  1212.  
  1213.